
<html><HEAD>
<LINK REL=STYLESHEET HREF="default.css" TYPE="text/css">
<TITLE>
SSL connections in PowerBuilder</TITLE>
</HEAD>
<BODY>

<!-- Header -->
<p class="ancestor" align="right"><A HREF="apptechp158.htm">Previous</A>&nbsp;&nbsp;<A HREF="apptechp160.htm" >Next</A>
<!-- End Header -->
<A NAME="CHDEJDFB"></A><h1>SSL connections in PowerBuilder</h1>
<A NAME="TI4960"></A><p>PowerBuilder provides two system objects for use with secure
connections:<A NAME="TI4961"></A>
<ul>
<li class=fi><b>SSLServiceProvider
service object</b>   The SSLServiceProvider object is an implementation of the <ABBR title = "e a server" >EAServer</ABBR> CtsSecurity::SSLServiceProvider interface.
For more information about this interface, you can view the <ABBR title = "e a server" >EAServer</ABBR> interface repository documentation
in a Web browser by connecting to your server at http://<i>hostname</i>:<i>portnumber</i>.<br>
You use the <b>GetGlobalProperty</b> and <b>SetGlobalProperty</b> functions
of the SSLServiceProvider object to configure global SSL properties. For a description
of the global properties you can set and/or get, see <A HREF="apptechp159.htm#BABBCBFJ">"SSL properties"</A>.<br><br>
You can also set SSL properties at the connection level by
specifying them in an options string for the Connection or JaguarORB
object. Interactive applications typically use the SSLServiceProvider
object in conjunction with the SSLCallback object. Applications
that run without user interaction typically configure SSL settings
at the connection level. For information about setting properties
at the connection level, see <A HREF="apptechp159.htm#CBHHDEHC">"ORB properties"</A>.<br></li>
<li class=ds><b>SSLCallback object</b>   To enable <ABBR title = "e a server" >EAServer</ABBR> to request
additional information from the client using a callback method,
you can implement your own logic for the callback methods in an
instance of the SSLCallBack object. The SSLCallback object is an
implementation of the <ABBR title = "e a server" >EAServer</ABBR> CtsSecurity::SSLCallback
interface. 
</li>
</ul>
</p>
<A NAME="BABBCBFJ"></A><h2>SSL properties</h2>
<A NAME="TI4962"></A><p><A HREF="apptechp159.htm#BABCFFDE">Table 25-1</A> lists
the properties that can be set or retrieved using <b>SetGlobalProperty</b> or <b>GetGlobalProperty</b>.
For any SSL connection, you must set the qop (quality of protection)
property and, unless you implement a callback to obtain it, you
must also set the pin property. You also need to connect to a server
address that can support your chosen level of security, as described
in <A HREF="apptechp159.htm#CHDCIBGB">"Secure server addresses"</A>.</p>
<p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>Setting global properties in a PowerBuilder session</span> <A NAME="TI4963"></A>When you run a client application in PowerBuilder, you can
set global properties only <i>once</i> during the
PowerBuilder session. You will need to restart PowerBuilder each
time you test the code that sets global SSL properties.</p>
<A NAME="TI4964"></A><p>If some properties are
not set or are set incorrectly, an SSL callback method is invoked.
If you do not specify an instance of the SSLCallback object, the default
callback implementation aborts the connection attempt.</p>
<A NAME="BABCFFDE"></A><table cellspacing=0 cellpadding=6 border=1 frame="void" rules="all"><caption>Table 25-1: List of SSL properties</caption>
<tr><th  rowspan="1"  ><A NAME="TI4965"></A>Property</th>
<th  rowspan="1"  ><A NAME="TI4966"></A>Description</th>
<th  rowspan="1"  ><A NAME="TI4967"></A>Get</th>
<th  rowspan="1"  ><A NAME="TI4968"></A>Set</th>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4969"></A>callbackImpl</td>
<td  rowspan="1"  ><A NAME="TI4970"></A>Instance of the SSLCallback object. For
more information, see <A HREF="apptechp161.htm#CIHBDGIC">"Using SSL callbacks"</A>.</td>
<td  rowspan="1"  ><A NAME="TI4971"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI4972"></A>Yes</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4973"></A>certificateLabel</td>
<td  rowspan="1"  ><A NAME="TI4974"></A>The client certificate to use if the
connection requires mutual authentication. The label is a simple
name that identifies an X.509 certificate/private key in
a PKCS #11 token. <A NAME="TI4975"></A><p>Required for mutual authentication. If not set and the connection requires
mutual authentication, invokes the <b>getCertificateLabel</b> callback
method, passing an array of available certificate names as an input
parameter.</p></td>
<td  rowspan="1"  ><A NAME="TI4976"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI4977"></A>Yes</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4978"></A>qop</td>
<td  rowspan="1"  ><A NAME="TI4979"></A>The name of a security characteristic
to use. Required for SSL. See <A HREF="apptechp159.htm#BABBGDIE">"Choosing a security characteristic"</A> for more information.</td>
<td  rowspan="1"  ><A NAME="TI4980"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI4981"></A>Yes</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4982"></A>cacheSize</td>
<td  rowspan="1"  ><A NAME="TI4983"></A>The size of the SSL session ID cache.
Default is 100.</td>
<td  rowspan="1"  ><A NAME="TI4984"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI4985"></A>Yes</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4986"></A>SessLingerTime</td>
<td  rowspan="1"  ><A NAME="TI4987"></A>The number of seconds that a session
ID entry is kept in the cache after the last connection that used
it is terminated. Default is 28800 seconds (8 hours).</td>
<td  rowspan="1"  ><A NAME="TI4988"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI4989"></A>Yes</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4990"></A>SessShareCount</td>
<td  rowspan="1"  ><A NAME="TI4991"></A>The number of concurrent SSL sessions
that can use the same session ID. Default is 10.</td>
<td  rowspan="1"  ><A NAME="TI4992"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI4993"></A>Yes</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4994"></A>pin</td>
<td  rowspan="1"  ><A NAME="TI4995"></A>The PKCS #11 token PIN.<A NAME="TI4996"></A><p>This is required for logging in to a PKCS #11 token
for client authentication and for retrieving trust information.
Required for SSL.</p><A NAME="TI4997"></A><p>If not set, set to <FONT FACE="Courier New">any</FONT>,
or set incorrectly, the <b>getPin</b> callback method
is invoked.</p></td>
<td  rowspan="1"  ><A NAME="TI4998"></A>No</td>
<td  rowspan="1"  ><A NAME="TI4999"></A>Yes</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI5000"></A>availableQop</td>
<td  rowspan="1"  ><A NAME="TI5001"></A>A list of available security characteristics.
The qop property can be set only to values that appear in this list.</td>
<td  rowspan="1"  ><A NAME="TI5002"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI5003"></A>No</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI5004"></A>availableQopDesc</td>
<td  rowspan="1"  ><A NAME="TI5005"></A>A list of descriptions for the available
security characteristics, in the same order as listed in the value
of the availableQop property.</td>
<td  rowspan="1"  ><A NAME="TI5006"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI5007"></A>No</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI5008"></A>availableVersions</td>
<td  rowspan="1"  ><A NAME="TI5009"></A>A list of SSL protocol versions supported
by the SSL runtime engine.</td>
<td  rowspan="1"  ><A NAME="TI5010"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI5011"></A>No</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI5012"></A>entrustReady</td>
<td  rowspan="1"  ><A NAME="TI5013"></A>TRUE if Entrust PKI software is available
on the client, FALSE otherwise.</td>
<td  rowspan="1"  ><A NAME="TI5014"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI5015"></A>No</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI5016"></A>entrustIniFile</td>
<td  rowspan="1"  ><A NAME="TI5017"></A>The path name for the Entrust INI file
that provides information on how to access Entrust. Required when
the <b>useEntrustid</b> property is set to true.<A NAME="TI5018"></A><p>If not set, the <b>getCredentialAttribute</b> callback
method is invoked.</p></td>
<td  rowspan="1"  ><A NAME="TI5019"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI5020"></A>Yes</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI5021"></A>entrustUserProfile</td>
<td  rowspan="1"  ><A NAME="TI5022"></A>The full path to the file containing
an Entrust user profile. Optional when the Entrust single-login
feature is available, required otherwise.<A NAME="TI5023"></A><p>If not set, the <b>getCredentialAttribute</b> callback
method is invoked.</p></td>
<td  rowspan="1"  ><A NAME="TI5024"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI5025"></A>Yes</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI5026"></A>useEntrustID</td>
<td  rowspan="1"  ><A NAME="TI5027"></A>Whether to use the Entrust ID or the
Sybase PKCS #11 token for authentication. This is a boolean
property. <A NAME="TI5028"></A><p>If this property is set to FALSE, Sybase PKCS #11
token properties are valid and Entrust-specific properties are ignored.
If this property is set to TRUE, Entrust-specific properties are
valid and Sybase PKCS #11 token properties are ignored.</p></td>
<td  rowspan="1"  ><A NAME="TI5029"></A>Yes</td>
<td  rowspan="1"  ><A NAME="TI5030"></A>Yes</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI5031"></A>entrustPassword</td>
<td  rowspan="1"  ><A NAME="TI5032"></A>The password for logging in to Entrust
with the specified user profile. Optional when the Entrust single-login
feature is available, required otherwise.<A NAME="TI5033"></A><p>If the password is required but not set or set incorrectly,
the <b>getPin</b> callback method is invoked.</p></td>
<td  rowspan="1"  ><A NAME="TI5034"></A>No</td>
<td  rowspan="1"  ><A NAME="TI5035"></A>Yes</td>
</tr>
</table>
<A NAME="BABBGDIE"></A><h4>Choosing a security characteristic</h4>
<A NAME="TI5036"></A><p>To use SSL, you must specify the name of an available security
characteristic for the qop property. The characteristic describes
the CipherSuites the client uses when negotiating an SSL connection.
When connecting, the client sends the list of CipherSuites that
it uses to the server, and the server selects a CipherSuite from
that list. The server chooses the first CipherSuite in the list that
it can use. If the server cannot use any of the available CipherSuites,
the connection fails.</p>
<A NAME="TI5037"></A><p>The <ABBR title = "e a server" >EAServer</ABBR> documentation
describes the security characteristics that are provided with <ABBR title = "e a server" >EAServer</ABBR>. You can retrieve a list
of characteristics available on the server and their descriptions
by retrieving the availableQop and availableQopDesc properties with <b>GetGlobalProperty</b>. </p>
<A NAME="CHDCIBGB"></A><h4>Secure server addresses</h4>
<A NAME="TI5038"></A><p>You can connect only to a server listener that uses a security
level that is equivalent to or greater than the level requested
in the qop setting. If you use <b>JaguarORB</b>.<b>string_to_object</b> to
instantiate a proxy for the SessionManager::Manager interface, the
listener specified by the server address must use a security profile
that matches the client's qop setting.</p>
<A NAME="CBHHDEHC"></A><h2>ORB properties</h2>
<A NAME="TI5039"></A><p>When you connect to <ABBR title = "e a server" >EAServer</ABBR> using
either the Connection object or the JaguarORB object, you are using
the <ABBR title = "e a server" >EAServer</ABBR> client ORB. You can
set its properties in the Options string of the Connection object
or using JaguarORB's <b>Init</b> function.
These are the ORB properties that apply specifically to secure connections:<A NAME="TI5040"></A>
<ul>
<li class=fi>ORBqop</li>
<li class=ds>ORBcertificateLabel</li>
<li class=ds>ORBpin</li>
<li class=ds>ORBuseEntrustID</li>
<li class=ds>ORBentrustPassword</li>
<li class=ds>ORBentrustIniFile</li>
<li class=ds>ORBentrustUserProfile
</li>
</ul>
</p>
<A NAME="TI5041"></A><p>The meaning of each of these properties is the same as that
of the corresponding SSL property, but the value affects only the
connection that is being established and not the entire session.
Set ORBqop to <FONT FACE="Courier New">sybpks_none</FONT> to prevent
any use of SSL on a connection. This setting is useful if you have
set the QOP globally for all ORBs using the SSLServiceProvider object,
and you want to override the QOP for a single connection.</p>
<A NAME="TI5042"></A><p>For a complete list of ORB properties, see the Help for the
Connection object.</p>
<A NAME="TI5043"></A><p>This example sets the ORBqop property to sybpks_simple
and specifies a log file: <p><PRE> myconnect.options = "ORBqop='sybpks_simple', " &amp;<br>   + "ORBLogFile='C:\tmp\log.txt'"</PRE></p>

